home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / perl5 / CGI::Push.z / CGI::Push
Encoding:
Text File  |  2002-10-03  |  10.0 KB  |  265 lines
  1.  
  2.  
  3.  
  4. CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))                                                      CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      CGI::Push - Simple Interface to Server Push
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.          use CGI::Push qw(:standard);
  13.  
  14.          do_push(-next_page=>\&next_page,
  15.                  -last_page=>\&last_page,
  16.                  -delay=>0.5);
  17.  
  18.          sub next_page {
  19.              my($q,$counter) = @_;
  20.              return undef if $counter >= 10;
  21.              return start_html('Test'),
  22.                     h1('Visible'),"\n",
  23.                     "This page has been called ", strong($counter)," times",
  24.                     end_html();
  25.            }
  26.  
  27.           sub last_page {
  28.               my($q,$counter) = @_;
  29.               return start_html('Done'),
  30.                      h1('Finished'),
  31.                      strong($counter),' iterations.',
  32.                      end_html;
  33.           }
  34.  
  35.  
  36. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  37.      CGI::Push is a subclass of the CGI object created by CGI.pm.  It is
  38.      specialized for server push operations, which allow you to create
  39.      animated pages whose content changes at regular intervals.
  40.  
  41.      You provide CGI::Push with a pointer to a subroutine that will draw one
  42.      page.  Every time your subroutine is called, it generates a new page.
  43.      The contents of the page will be transmitted to the browser in such a way
  44.      that it will replace what was there beforehand.  The technique will work
  45.      with HTML pages as well as with graphics files, allowing you to create
  46.      animated GIFs.
  47.  
  48. UUUUSSSSIIIINNNNGGGG CCCCGGGGIIII::::::::PPPPuuuusssshhhh
  49.      CGI::Push adds one new method to the standard CGI suite, _d_o__p_u_s_h().  When
  50.      you call this method, you pass it a reference to a subroutine that is
  51.      responsible for drawing each new page, an interval delay, and an optional
  52.      subroutine for drawing the last page.  Other optional parameters include
  53.      most of those recognized by the CGI _h_e_a_d_e_r() method.
  54.  
  55.      You may call _d_o__p_u_s_h() in the object oriented manner or not, as you
  56.      prefer:
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))                                                      CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))
  71.  
  72.  
  73.  
  74.          use CGI::Push;
  75.          $q = new CGI::Push;
  76.          $q->do_push(-next_page=>\&draw_a_page);
  77.  
  78.              -or-
  79.  
  80.          use CGI::Push qw(:standard);
  81.          do_push(-next_page=>\&draw_a_page);
  82.  
  83.      Parameters are as follows:
  84.  
  85.      -next_page
  86.  
  87.              do_push(-next_page=>\&my_draw_routine);
  88.  
  89.          This required parameter points to a reference to a subroutine
  90.          responsible for drawing each new page.  The subroutine should expect
  91.          two parameters consisting of the CGI object and a counter indicating
  92.          the number of times the subroutine has been called.  It should return
  93.          the contents of the page as an aaaarrrrrrrraaaayyyy of one or more items to print.
  94.          It can return a false value (or an empty array) in order to abort the
  95.          redrawing loop and print out the final page (if any)
  96.  
  97.              sub my_draw_routine {
  98.                  my($q,$counter) = @_;
  99.                  return undef if $counter > 100;
  100.                  return start_html('testing'),
  101.                         h1('testing'),
  102.                         "This page called $counter times";
  103.              }
  104.  
  105.          You are of course free to refer to create and use global variables
  106.          within your draw routine in order to achieve special effects.
  107.  
  108.      -last_page
  109.          This optional parameter points to a reference to the subroutine
  110.          responsible for drawing the last page of the series.  It is called
  111.          after the -next_page routine returns a false value.  The subroutine
  112.          itself should have exactly the same calling conventions as the
  113.          -next_page routine.
  114.  
  115.      -type
  116.          This optional parameter indicates the content type of each page.  It
  117.          defaults to "text/html".  Normally the module assumes that each page
  118.          is of a homogenous MIME type.  However if you provide either of the
  119.          magic values "heterogeneous" or "dynamic" (the latter provided for
  120.          the convenience of those who hate long parameter names), you can
  121.          specify the MIME type -- and other header fields -- on a per-page
  122.          basis.  See "heterogeneous pages" for more details.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))                                                      CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))
  137.  
  138.  
  139.  
  140.      -delay
  141.          This indicates the delay, in seconds, between frames.  Smaller delays
  142.          refresh the page faster.  Fractional values are allowed.
  143.  
  144.          IIIIffff nnnnooootttt ssssppppeeeecccciiiiffffiiiieeeedddd,,,, ----ddddeeeellllaaaayyyy wwwwiiiillllllll ddddeeeeffffaaaauuuulllltttt ttttoooo 1111 sssseeeeccccoooonnnndddd
  145.  
  146.      -cookie, -target, -expires
  147.          These have the same meaning as the like-named parameters in
  148.          _C_G_I::_h_e_a_d_e_r().
  149.  
  150.      HHHHeeeetttteeeerrrrooooggggeeeennnneeeeoooouuuussss PPPPaaaaggggeeeessss
  151.  
  152.      Ordinarily all pages displayed by CGI::Push share a common MIME type.
  153.      However by providing a value of "heterogeneous" or "dynamic" in the
  154.      _d_o__p_u_s_h() -type parameter, you can specify the MIME type of each page on
  155.      a case-by-case basis.
  156.  
  157.      If you use this option, you will be responsible for producing the HTTP
  158.      header for each page.  Simply modify your draw routine to look like this:
  159.  
  160.          sub my_draw_routine {
  161.              my($q,$counter) = @_;
  162.              return header('text/html'),   # note we're producing the header here
  163.                     start_html('testing'),
  164.                     h1('testing'),
  165.                     "This page called $counter times";
  166.          }
  167.  
  168.      You can add any header fields that you like, but some (cookies and status
  169.      fields included) may not be interpreted by the browser.  One interesting
  170.      effect is to display a series of pages, then, after the last page, to
  171.      redirect the browser to a new URL.  Because _r_e_d_i_r_e_c_t() does b<not> work,
  172.      the easiest way is with a -refresh header field, as shown below:
  173.  
  174.          sub my_draw_routine {
  175.              my($q,$counter) = @_;
  176.              return undef if $counter > 10;
  177.              return header('text/html'),   # note we're producing the header here
  178.                     start_html('testing'),
  179.                     h1('testing'),
  180.                     "This page called $counter times";
  181.          }
  182.  
  183.          sub my_last_page {
  184.              header(-refresh=>'5; URL=http://somewhere.else/finished.html',
  185.                     -type=>'text/html'),
  186.              start_html('Moved'),
  187.              h1('This is the last page'),
  188.              'Goodbye!'
  189.               hr,
  190.               end_html;
  191.          }
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))                                                      CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))
  203.  
  204.  
  205.  
  206.      CCCChhhhaaaannnnggggiiiinnnngggg tttthhhheeee PPPPaaaaggggeeee DDDDeeeellllaaaayyyy oooonnnn tttthhhheeee FFFFllllyyyy
  207.  
  208.      If you would like to control the delay between pages on a page-by-page
  209.      basis, call _p_u_s_h__d_e_l_a_y() from within your draw routine.  _p_u_s_h__d_e_l_a_y()
  210.      takes a single numeric argument representing the number of seconds you
  211.      wish to delay after the current page is displayed and before displaying
  212.      the next one.  The delay may be fractional.  Without parameters,
  213.      _p_u_s_h__d_e_l_a_y() just returns the current delay.
  214.  
  215. IIIINNNNSSSSTTTTAAAALLLLLLLLIIIINNNNGGGG CCCCGGGGIIII::::::::PPPPuuuusssshhhh SSSSCCCCRRRRIIIIPPPPTTTTSSSS
  216.      Server push scripts mmmmuuuusssstttt be installed as no-parsed-header (NPH) scripts
  217.      in order to work correctly.  On Unix systems, this is most often
  218.      accomplished by prefixing the script's name with "nph-". Recognition of
  219.      NPH scripts happens automatically with WebSTAR and Microsoft IIS.  Users
  220.      of other servers should see their documentation for help.
  221.  
  222. CCCCAAAAVVVVEEEEAAAATTTTSSSS
  223.      This is a new module.  It hasn't been extensively tested.
  224.  
  225. AAAAUUUUTTTTHHHHOOOORRRR IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNN
  226.      be used and modified freely, but I do request that this copyright notice
  227.      remain attached to the file.  You may modify this module as you wish, but
  228.      if you redistribute a modified version, please attach a note listing the
  229.      modifications you have made.
  230.  
  231.      Address bug reports and comments to:  lstein@genome.wi.mit.edu
  232.  
  233. BBBBUUUUGGGGSSSS
  234.      This section intentionally left blank.
  235.  
  236. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  237.      the _C_G_I::_C_a_r_p manpage, the _C_G_I manpage
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.